home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / exampleCode / GLX / DBglxwidgetOpenGL / README < prev   
Encoding:
Text File  |  1994-08-02  |  12.1 KB  |  348 lines
  1. /*****************************************************************************/
  2. /* NEW GLX WIDGET DESCRIPTION                             */
  3. /* Date:    01-03-94                              */
  4. /* Authors:    Ed Millard                                                 */
  5. /*              Chris Carlson                                     */
  6. /*              Michael Gold                                     */
  7. /*              Glenn Shute                                     */
  8. /*****************************************************************************/
  9.  
  10. This directory contains source for another new version of the SGI GLX mixed
  11. mode Xt widget (GlxDraw) and the GLX mixed mode Motif widget
  12. (GlxMDraw).  The Motif widget is identical to the Xt version except
  13. with the addition of the Primitive base class and the Motif interface.
  14. These widgets, like their predecessor GlxDraw and GlxMDraw widgets,
  15. allows the use of GL within X windows with Xt and Motif applications.
  16. This new version has now been ported to OpenGL as well.  Compile
  17. options select GL or OpenGL versions of the widget and the overlay test 
  18. program. 
  19.  
  20. This version also allows switching between single and double buffering
  21. in the GL window by using XtSetValues.  Its intent is to reduce the
  22. application programming required to use single and double buffer in a
  23. mixed mode application.
  24.  
  25. The OpenGL version has not been extensively tested but appears basically
  26. functional on:
  27.  
  28.    XZ
  29.    Elan
  30.    Extereme
  31.  
  32. There are known problems with the OpenGL version on RealityEngine.  This
  33. is being investigated.
  34.  
  35. Use at your own risk, but I would be interested in hearing
  36. suggestions and complaints.  Send these to:
  37.  
  38.      millard@sgi.com
  39.  
  40. Some work has been done to add support for a switch to stereo mode
  41. inside the widget.  This is not implemented under GL and is not working
  42. under OpenGL yet (hopefully optional stereo support will be added in the
  43. next release of this widget.  OpenGL stereo in the widget depends on stereo
  44. support in OpenGL which is not available for the most part yet).
  45.  
  46. REQUIREMENTS
  47. ------------
  48.  
  49. These widgets should work under:
  50.  
  51.     X11R4    Motif 1.1    IRIX 4.0.x
  52.     X11R5    Motif 1.2    IRIX 5.x
  53.  
  54. The OpenGL version will only work on IRIX 5.1+ on platforms which support
  55. OpenGL.
  56.  
  57. DEMO MAKE
  58. ---------
  59.  
  60. Run make in this directory to rebuild the library libsgiw.a,
  61. containing both the GlxDraw and GlxMDraw widgets.
  62.  
  63. By default the flag -DUSE_GL is set so you will get the GL version of
  64. the widget.   There are option lines in the Makefile to switch to the
  65. OpenGL version.  You need to comment out two lines and uncomment the other
  66. two lines to switch between GL and OpenGL.
  67.  
  68. APPLICATION MAKE
  69. ----------------
  70.  
  71. To use this new widget you must include the "GlxDraw.h" (or
  72. "GlxMDraw.h" for Motif) from this directory and not the one in
  73. /usr/include/X11/Xirisw.
  74.  
  75. You must link with GlxDraw.o or GlxMDraw.o (for Xt version or Motif
  76. version respectively) or the libsgiw.a library from this directory
  77. instead of libXirisw.a. 
  78.  
  79. The objects or the archive should be placed ahead of IRIX archives
  80. or DSO's like -lGL or -lgl.  In particular on IRIX 5 -lGL or
  81. -lgl may pull in /usr/lib/Xirisw if they are referenced before
  82. GlxDraw.o, GlxMDraw.o or libsgiw.a.
  83.  
  84. USAGE
  85. -----
  86.  
  87. The example code below is provided to demonstrate how to create a
  88. Motif GL widget.  Similar code can be used to create the Xt version.
  89.  
  90. GLXconfig structure in GL:
  91. --------------------
  92. The first step in creating a mixed-model widget is creating a
  93. GLXconfig structure describing the type of GL window you need.  This
  94. structure should describe the normal window and any overlay, underlay
  95. or popup windows that will be required.
  96.  
  97. NOTE: When requesting both double and single buffering, you MUST
  98. request a single buffered window in the GLXconfig structure.  Since
  99. the double buffered window will be a child of the single buffered
  100. window, it is important that the parent have more bitplanes than the
  101. child.
  102.  
  103. Here is an example of defining a GLXconfig structure for GL:
  104.  
  105.     static GLXconfig glxConfig [] = {
  106.         { GLX_NORMAL, GLX_DOUBLE, FALSE },
  107.         { GLX_NORMAL, GLX_RGB, FALSE },
  108.         { GLX_OVERLAY, GLX_BUFSIZE, 2 },
  109.         { 0, 0, 0 }
  110.     };
  111.  
  112. This GLXconfig structure requests a single buffered window, running in
  113. colormap mode with an overlay window having a depth of 2.
  114.  
  115. GLXconfig in OpenGL:
  116. ------------------
  117.  
  118. For OpenGL you should specify and attribute lists like these:
  119.  
  120. static int glxConfig[] = {
  121.     GLX_RGBA,
  122.     GLX_RED_SIZE,3,
  123.     GLX_BLUE_SIZE,3,
  124.     GLX_GREEN_SIZE,3,
  125.     GLX_DEPTH_SIZE,12,
  126.     None,
  127. };
  128. static int glxConfigOverlay[] = {
  129.     GLX_LEVEL, 1,
  130.     GLX_BUFFER_SIZE, 4,
  131.     None
  132. };
  133.  
  134. These are documented in the man page for glXChooseVisual. 
  135.  
  136. glxConfigOverlay is required if you want an overlay window.  If its not
  137. specified you wont get an overlay window.
  138.  
  139. Setting resources in GL:
  140. ------------------
  141. The following code excerpt shows how to request a GLX widget that is
  142. single buffered (default window), colormapped and has overlay planes.
  143. It also enables the double buffered window.  It assumes the GLXconfig
  144. structure shown above.
  145.  
  146.     n = 0;
  147.     XtSetArg (args[n], GlxNglxConfig, glxConfig); n++;
  148.     XtSetArg (args[n], GlxNuseOverlay, TRUE); n++;
  149.     XtSetArg (args[n], GlxNprovideSingleBuffer, TRUE); n++;
  150.     glw = XtCreateManagedWidget("glwidget", glxMDrawWidgetClass,
  151.                                     frame, args, n);
  152.  
  153. The first resource defines the GLXconfig structure to use.  The second
  154. resource requests the overlay planes.  The third resource indicates we
  155. also want the double buffered window.
  156.  
  157. Setting resources in OpenGL:
  158. ------------------
  159.  
  160. For OpenGL the procedure is similar but slightly different.
  161.  
  162.    XtSetArg(args[n], GlxNglxConfig, glxConfig); n++;
  163.    XtSetArg(args[n], GlxNoverlayGlxConfig, glxConfigOverlay); n++;
  164.    glw = XtCreateManagedWidget("glwidget", glxMDrawWidgetClass,
  165.                                     frame, args, n);
  166.  
  167. The main difference here is that GlxNuseOverlay is no longer used.
  168. You need to specify an attribute list for the overlay buffer.  If an
  169. attribute list is specified an overlay buffer will be provided.  If there
  170. is no attribute list there will be no overlay.
  171.  
  172. Switching single/double buffering:
  173. ----------------------------------
  174. To switch to double buffer mode:
  175.  
  176.         n = 0;
  177.             XtSetArg (args[n], GlxNsingleBuffer, FALSE); n++;
  178.             XtSetValues (w, args, n);
  179.  
  180. To switch to single buffer mode:
  181.  
  182.         n = 0;
  183.             XtSetArg (args[n], GlxNsingleBuffer, TRUE); n++;
  184.             XtSetValues (w, args, n);
  185.  
  186.  
  187. DEMO PROGRAM USAGE
  188. ------------------
  189.  
  190. The program overlay.c is a modification of the program overlay.c provided
  191. in 4Dgifts.  If the symbol USE_NEW_WIDGET is not defined, it should
  192. work exactly like overlay.c.  With the symbol defined, the mouse
  193. buttons work as follows:
  194.  
  195.     Left    - Move the car in the main window
  196.     Middle    - Selects single buffering
  197.     Right    - Selects double buffering
  198.  
  199. The house is in the overlay planes.  The car is drawn in the normal
  200. planes and will flicker in single buffer mode.
  201.  
  202. MORE WORK REQUIRED
  203. ------------------
  204.  
  205. When switching from one buffering mode to the other, much of the GL
  206. context set up in the old window is saved and restored into the new
  207. window.  (Lighting, materials and textures must be done by the
  208. application.)  It would be nice to be able to have a resource that
  209. indicates when this operation must be done so it isn't done every
  210. time.
  211.  
  212. When switching from one buffering mode to the other OpenGL only these
  213. part sof the context are copied between the old and new context:
  214.  
  215.     GL_MODELVIEW    Matrix
  216.     GL_PROJECTION   Matrix
  217.     GL_VIEWPORT
  218.  
  219. This is considerable less info between copied in the GL version of the
  220. widget.  Feedback is desired on what should and shouldn't be copied
  221. between contexts when switching.  Or you can easily change the stuff you
  222. want to copy by modifing SetNewWindow in GlxDraw.c.
  223.  
  224. If an overlay is present these are copied between the Overlay contexts
  225. also.
  226.  
  227. You will be in GL_MODELVIEW after a switch
  228.  
  229. BUGS
  230. ----
  231.  
  232. None known at this time.
  233.  
  234.  
  235. CAUTIONS
  236. --------
  237.  
  238. Resize
  239. ------
  240. At present I'm generating a resize callback for each set of windows so
  241. that the app can resize the viewport, for instance.  However you won't
  242. get an expose/redraw on the inactive window.
  243.  
  244. Two window implementation
  245. -------------------------
  246. This implementation uses two different windows for single and double
  247. buffering.  If auxiliary windows are used (i.e.  overlays, popups)
  248. they will also be duplicated, with a set parented off the double
  249. buffer window and another set off the single buffer window.
  250.  
  251. When a buffering mode switch occurs the core X window in the widget is
  252. swapped.  This is done so that event handlers transparently switch to
  253. the new GL window.  The only way to get around this switch is to
  254. figure out a portable way to switch buffering modes within one window
  255. which hasn't worked out yet.
  256.  
  257. This core window switch may cause problems in the following areas:
  258.  
  259. 1.    If you get and save the core X window and try to use it when
  260.     it is not active.  Using XtWindow will always return the
  261.     correct core window and is highly recommended.
  262.  
  263. 2.    This implementation hasn't been tested with X children
  264.     attached to the GLX widget.  I don't think this is common
  265.     practice since windows are usually parented off of the window
  266.     above the GLX widget.  When time permits I will work on
  267.     reparenting children so this will work.
  268.  
  269. Colormaps
  270. ---------
  271. The resource GlxNoverrideColormap controls the behavior of installing
  272. colormaps at instantiation time.  It is rather confusing how it works,
  273. though it works the same for this widget as for the standard GlxDraw
  274. and GlxMDraw widgets.
  275.  
  276. By default GlxNoverrideColormap is set to TRUE.  This means that the
  277. colormap provided in the GLXconfig structure (returned when the widget
  278. calls GLXgetconfig) will override the default colormap (which is
  279. usually from the parent).
  280.  
  281. If the application wants to provide its own colormap at instantiation
  282. time, it must set XtNcolormap to this colormap and set
  283. GlxNoverrideColormap to FALSE.
  284.  
  285. When creating the single and double buffered widget, the application
  286. must also set the colormap for GlxNaltColormap, which will be used for
  287. the secondary window.
  288.  
  289. HINTS:  If the application wants to use their own colormaps, it is
  290. usually desireable to find out what visuals will be assigned when the
  291. widget is realized.  The application can find this out by calling
  292. GLXgetconfig itself.  GLXgetconfig does nothing but build a table
  293. which is returned to the application with all the values filled in,
  294. rather than just the ones specified by the application.  This table
  295. can be scanned for buffer=GLX_NORMAL and mode=GLX_COLORMAP to find out
  296. the colormap that will be assigned and buffer=GLX_NORMAL and
  297. mode=GLX_VISUAL to find out the visual that will be assigned.  By
  298. changing the value of buffer=GLX_NORMAL and mode=GLX_DOUBLE, the same
  299. information can be determined for the secondary window.
  300.  
  301.  
  302. NEW RESOURCES
  303. -------------
  304.  
  305. The following lists and describes the new resources provided with this
  306. new version of the GLX widget:
  307.  
  308. GlxNprovideSingleBuffer
  309.     Class = GlxCProvideSingleBuffer
  310.     Type  = XtRBoolean
  311.  
  312.     This resource is used only on instantiation of the widget.  It
  313.     indicates whether both a double buffered and single buffered
  314.     window are required.
  315.  
  316.     WARNING: If set to TRUE, be sure that the GLXconfig structure
  317.     requests a single buffered window.  Also, see the description
  318.     for GlxNaltColormap below.
  319.  
  320. GlxNmainWindow
  321.     Class = GlxCWindow
  322.     Type  = XtRWindow
  323.  
  324.     This resource is filled with the window ID of the primary window.
  325.  
  326. GlxNsingleBuffer
  327.     Class = GlxCSingleBuffer
  328.     Type  = XtRBoolean
  329.  
  330.     This resource identifies which window is currently mapped.  If
  331.     TRUE, the single buffered window is mapped.  It is also used to
  332.     set which window is to be mapped, using XtSetValues.
  333.  
  334. GlxNaltColormap
  335.     Class = GlxCColormap
  336.     Type  = XtRColormap
  337.  
  338.     This resource contains the colormap of the secondary window.
  339.     After instantiating the widget, it will be filled with the
  340.     colormap.  If the application wants to set the colormap for the
  341.     secondary window, this needs to be set to the colormap ID for the
  342.     secondary window.
  343.  
  344.     WARNING: To have this entry paid attention to, the resource
  345.     GlxNoverrideColormap must be set to FALSE (default is TRUE).  If
  346.     this is done, the core colormap (XtNcolormap) must also be set
  347.     with a colormap for the primary window.
  348.